package com.zenithmind.document.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.document.pojo.domain.DocumentFavorite;
import com.zenithmind.document.pojo.query.DocumentFavoriteQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentFavoriteVO;

import java.util.List;

/**
 * 文档收藏服务接口
 * 遵循接口隔离原则：专注于收藏功能
 * 遵循单一职责原则：只负责文档收藏相关操作
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentFavoriteService extends IService<DocumentFavorite> {

    /**
     * 收藏文档
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 是否成功
     */
    Boolean favoriteDocument(String documentId, String userId, String folderName);

    /**
     * 取消收藏文档
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean unfavoriteDocument(String documentId, String userId);

    /**
     * 批量收藏文档
     * 
     * @param documentIds 文档ID列表
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 成功数量
     */
    Integer batchFavoriteDocuments(List<String> documentIds, String userId, String folderName);

    /**
     * 批量取消收藏文档
     * 
     * @param documentIds 文档ID列表
     * @param userId 用户ID
     * @return 成功数量
     */
    Integer batchUnfavoriteDocuments(List<String> documentIds, String userId);

    /**
     * 检查文档是否已收藏
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否已收藏
     */
    Boolean isFavorited(String documentId, String userId);

    /**
     * 分页查询用户收藏
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentFavoriteVO> getFavoritePage(DocumentFavoriteQueryDTO queryDTO);

    /**
     * 获取用户收藏列表
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @param limit 限制数量
     * @return 收藏列表
     */
    List<DocumentFavoriteVO> getUserFavorites(String userId, String folderName, Integer limit);

    /**
     * 获取文档收藏用户列表
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 用户列表
     */
    List<DocumentFavoriteVO> getDocumentFavoriteUsers(String documentId, Integer limit);

    /**
     * 获取用户收藏夹列表
     * 
     * @param userId 用户ID
     * @return 收藏夹列表
     */
    List<String> getUserFavoriteFolders(String userId);

    /**
     * 创建收藏夹
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @param description 描述
     * @return 是否成功
     */
    Boolean createFavoriteFolder(String userId, String folderName, String description);

    /**
     * 删除收藏夹
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 是否成功
     */
    Boolean deleteFavoriteFolder(String userId, String folderName);

    /**
     * 重命名收藏夹
     * 
     * @param userId 用户ID
     * @param oldFolderName 旧收藏夹名称
     * @param newFolderName 新收藏夹名称
     * @return 是否成功
     */
    Boolean renameFavoriteFolder(String userId, String oldFolderName, String newFolderName);

    /**
     * 移动收藏到其他收藏夹
     * 
     * @param favoriteIds 收藏ID列表
     * @param targetFolderName 目标收藏夹名称
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean moveFavoritesToFolder(List<String> favoriteIds, String targetFolderName, String userId);

    /**
     * 搜索用户收藏
     * 
     * @param userId 用户ID
     * @param keyword 关键词
     * @param limit 限制数量
     * @return 收藏列表
     */
    List<DocumentFavoriteVO> searchUserFavorites(String userId, String keyword, Integer limit);

    /**
     * 获取收藏统计信息
     * 
     * @param userId 用户ID
     * @return 统计信息
     */
    Object getFavoriteStatistics(String userId);

    /**
     * 获取热门收藏文档
     * 
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> getHotFavoriteDocuments(Integer limit);

    /**
     * 获取最近收藏
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 收藏列表
     */
    List<DocumentFavoriteVO> getRecentFavorites(String userId, Integer limit);

    /**
     * 导出用户收藏
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 导出数据
     */
    Object exportUserFavorites(String userId, String folderName);

    /**
     * 导入用户收藏
     * 
     * @param userId 用户ID
     * @param importData 导入数据
     * @return 导入数量
     */
    Integer importUserFavorites(String userId, Object importData);

    /**
     * 清理无效收藏
     * 
     * @return 清理数量
     */
    Integer cleanupInvalidFavorites();

    /**
     * 同步收藏统计
     * 
     * @param documentId 文档ID
     * @return 是否成功
     */
    Boolean syncFavoriteStatistics(String documentId);
}
